/*=============================================================================*
 *  Copyright 2004 The Apache Software Foundation
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 *=============================================================================*/
package topics.expression;

import topics.Topic;
import topics.TopicSpaceSet;
import topics.expression.InvalidTopicExpressionException;
import topics.expression.TopicExpression;
import topics.expression.TopicExpressionException;
import topics.expression.TopicExpressionResolutionException;
import topics.expression.TopicPathDialectUnknownException;

/**
 * The <code>TopicExpressionEngine</code> interface is used to map queries on a
 * topic list to the appropriate <code>TopicExpressionEvaluators</code> and then
 * return the result. <code>TopicExpressionEvaluators</code> can be
 * preconfigured or dynamically added at runtime.
 *
 * @see TopicExpressionEvaluator
 */
public interface TopicExpressionEngine
{
   /**
    * Gets the evaluator currently registered to handle a topic expression of
    * the specified dialect.
    *
    * @return the matching topic expression evaluator or null if none was
    *         found
    */
   TopicExpressionEvaluator getEvaluator( String dialect );

   /**
    * Returns a list of URIs representing the registered topic expression
    * dialects
    *
    * @return the list of supported dialects
    */
   String[] getSupportedDialects(  );

   /**
    * Resolves a topic expression using the passed topic list. The appropraite
    * TopicExpressionEvaluator is used based on the dialect element.
    *
    * @param topicSpaceSet       the topic list to apply the expression to
    * @param topicExpression topic expression
    * @return the set of topics the expression evaluated to
    * @throws org.apache.ws.notification.topics.expression.TopicPathDialectUnknownException
    *                                  if the topic expression dialect is not
    *                                  supported
    * @throws TopicExpressionResolutionException
    *                                  if the expression could not be
    *                                  evaluated
    * @throws InvalidTopicExpressionException
    *                                  if the topic expression is invalid
    * @throws TopicExpressionException if any other error occurs
    */
   Topic[] evaluateTopicExpression( TopicSpaceSet   topicSpaceSet,
                                    TopicExpression topicExpression )
   throws TopicPathDialectUnknownException, 
          TopicExpressionResolutionException, 
          InvalidTopicExpressionException, 
          TopicExpressionException;

   /**
    * registers a new evaluator that can be used to evaluate topic expressions
    *
    * @param evaluator implementation of evaluator to be used for evaluating
    *                  topic expressions
    */
   void registerEvaluator( TopicExpressionEvaluator evaluator );
}